<!doctype html>


<html>
<head>
  <link rel="shortcut icon" href="static/images/favicon.ico" type="image/x-icon">
  <title>safeurl.js (Closure Library API Documentation - JavaScript)</title>
  <link rel="stylesheet" href="static/css/base.css">
  <link rel="stylesheet" href="static/css/doc.css">
  <link rel="stylesheet" href="static/css/sidetree.css">
  <link rel="stylesheet" href="static/css/prettify.css">

  <script>
     var _staticFilePath = "static/";
     var _typeTreeName = "goog";
     var _fileTreeName = "Source";
  </script>

  <script src="static/js/doc.js">
  </script>


  <meta charset="utf8">
</head>

<body onload="grokdoc.onLoad();">

<div id="header">
  <div class="g-section g-tpl-50-50 g-split">
    <div class="g-unit g-first">
      <a id="logo" href="index.html">Closure Library API Documentation</a>
    </div>

    <div class="g-unit">
      <div class="g-c">
        <strong>Go to class or file:</strong>
        <input type="text" id="ac">
      </div>
    </div>
  </div>
</div>





<div class="colmask rightmenu">
<div class="colleft">
    <div class="col1">
      <!-- Column 1 start -->

<div id="title">
       <span class="fn">safeurl.js</span>
</div>

<div class="g-section g-tpl-75-25">
  <div class="g-unit g-first" id="description">
    <span class='nodesc'>No description.</span>
  </div>
  

        <div class="g-unit" id="useful-links">
          <div class="title">Useful links</div>
          <ol>
            <li><a href="local_closure_goog_html_safeurl.js.source.html"><span class='source-code-link'>Source Code</span></a></li>
            <li><a href="http://code.google.com/p/closure-library/source/browse/local/closure/goog/html/safeurl.js">Git</a></li>
          </ol>
        </div>
</div>

<h2 class="g-first">File Location</h2>
  <div class="g-section g-tpl-20-80">
    <div class="g-unit g-first">
      <div class="g-c-cell code-label">/goog/html/safeurl.js</div>
    </div>
  </div>
<hr/>


  <h2>Classes</h2>
 <div class="fn-constructor">
        <a href="class_goog_html_SafeUrl.html">
          goog.html.SafeUrl</a><br/>
        <div class="class-details">A string that is safe to use in URL context in DOM APIs and HTML documents.

A SafeUrl is a string-like object that carries the security type contract
that its value as a string will not cause untrusted script execution
when evaluated as a hyperlink URL in a browser.

Values of this type are guaranteed to be safe to use in URL/hyperlink
contexts, such as, assignment to URL-valued DOM properties, or
interpolation into a HTML template in URL context (e.g., inside a href
attribute), in the sense that the use will not result in a
Cross-Site-Scripting vulnerability.

Note that, as documented in <code> goog.html.SafeUrl.unwrap</code>, this type's
contract does not guarantee that instances are safe to interpolate into HTML
without appropriate escaping.

Note also that this type's contract does not imply any guarantees regarding
the resource the URL refers to.  In particular, SafeUrls are <b>not</b>
safe to use in a context where the referred-to resource is interpreted as
trusted code, e.g., as the src of a script tag.

Instances of this type must be created via the factory methods
(<code> goog.html.SafeUrl.from</code>, <code> goog.html.SafeUrl.sanitize</code>), etc and
not by invoking its constructor.  The constructor intentionally takes no
parameters and the type is immutable; hence only a default instance
corresponding to the empty string can be obtained via constructor invocation.

</div>
 </div>
      
<br/>

  <div class="legend">
        <span class="key publickey"></span><span>Public</span>
        <span class="key protectedkey"></span><span>Protected</span>
        <span class="key privatekey"></span><span>Private</span>
  </div>









<div class="section">
  <table class="horiz-rule">


  </table>
</div>




  <h2>Global Functions</h2>





<div class="section">
  <table class="horiz-rule">


     <tr class="even entry private">
       <td class="access"></td>






  <td>
    <a name="goog.html.SafeUrl.createSafeUrlSecurityPrivateDoNotAccessOrElse_"></a>


     <div class="arg">
       <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.html.SafeUrl.</span><span class="entryName">createSafeUrlSecurityPrivateDoNotAccessOrElse_<span class="args">(<span class="arg">url</span>)</span>
        </span>
        &#8658; <span>!</span><span class="type"><a href="class_goog_html_SafeUrl.html">goog.html.SafeUrl</a></span>
      </div>


     <div class="entryOverview">
       Utility method to create SafeUrl instances.

This function is considered "package private", i.e. calls (using "suppress
visibility") from other files within this package are considered acceptable.
DO NOT call this function from outside the goog.html package; use appropriate
wrappers instead.


     </div>


    <! -- Method details -->
    <div class="entryDetails">

      <div class="detailsSection">
        <b>Arguments: </b>






<table class="horiz-rule">
     
   <tr class="even">
     <td>
        <span class="entryName">url</span>
        : <span class="type"><a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/String">string</a></span>
        <div class="entryOverview">The string to initialize the SafeUrl object with.</div>
     </td>
   </tr>
  </table>
      </div>
   
      <div class="detailsSection">
        <b>Returns:</b>&nbsp;<span>!</span><span class="type"><a href="class_goog_html_SafeUrl.html">goog.html.SafeUrl</a></span>&nbsp;
            The initialized SafeUrl object.
      </div>
  
    </div>
   
  </td>


  <td class="view-code">
     <a href="local_closure_goog_html_safeurl.js.source.html#line402">code &raquo;</a>
  </td>
     </tr>


     <tr class="odd entry public">
       <td class="access"></td>






  <td>
    <a name="goog.html.SafeUrl.fromConstant"></a>


     <div class="arg">
       <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.html.SafeUrl.</span><span class="entryName">fromConstant<span class="args">(<span class="arg">url</span>)</span>
        </span>
        &#8658; <span>!</span><span class="type"><a href="class_goog_html_SafeUrl.html">goog.html.SafeUrl</a></span>
      </div>


     <div class="entryOverview">
       Creates a SafeUrl object from a compile-time constant string.

Compile-time constant strings are inherently program-controlled and hence
trusted.


     </div>


    <! -- Method details -->
    <div class="entryDetails">

      <div class="detailsSection">
        <b>Arguments: </b>






<table class="horiz-rule">
     
   <tr class="even">
     <td>
        <span class="entryName">url</span>
        : <span>!</span><span class="type"><a href="class_goog_string_Const.html">goog.string.Const</a></span>
        <div class="entryOverview">A compile-time-constant string from which to
        create a SafeUrl.</div>
     </td>
   </tr>
  </table>
      </div>
   
      <div class="detailsSection">
        <b>Returns:</b>&nbsp;<span>!</span><span class="type"><a href="class_goog_html_SafeUrl.html">goog.html.SafeUrl</a></span>&nbsp;
            A SafeUrl object initialized to <code> url</code>.
      </div>
  
    </div>
   
  </td>


  <td class="view-code">
     <a href="local_closure_goog_html_safeurl.js.source.html#line238">code &raquo;</a>
  </td>
     </tr>


     <tr class="even entry private">
       <td class="access"></td>






  <td>
    <a name="goog.html.SafeUrl.normalize_"></a>


     <div class="arg">
       <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.html.SafeUrl.</span><span class="entryName">normalize_<span class="args">(<span class="arg">url</span>)</span>
        </span>
        &#8658; <span class="type"><a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/String">string</a></span>
      </div>


     <div class="entryOverview">
       Normalizes <code> url</code> the UTF-8 encoding of url, using a whitelist of
characters. Whitelisted characters are not percent-encoded.

     </div>


    <! -- Method details -->
    <div class="entryDetails">

      <div class="detailsSection">
        <b>Arguments: </b>






<table class="horiz-rule">
     
   <tr class="even">
     <td>
        <span class="entryName">url</span>
        : <span class="type"><a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/String">string</a></span>
        <div class="entryOverview">The URL to normalize.</div>
     </td>
   </tr>
  </table>
      </div>
   
      <div class="detailsSection">
        <b>Returns:</b>&nbsp;<span class="type"><a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/String">string</a></span>&nbsp;
            The normalized URL.
      </div>
  
    </div>
   
  </td>


  <td class="view-code">
     <a href="local_closure_goog_html_safeurl.js.source.html#line328">code &raquo;</a>
  </td>
     </tr>


     <tr class="odd entry public">
       <td class="access"></td>






  <td>
    <a name="goog.html.SafeUrl.sanitize"></a>


     <div class="arg">
       <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.html.SafeUrl.</span><span class="entryName">sanitize<span class="args">(<span class="arg">url</span>)</span>
        </span>
        &#8658; <span>!</span><span class="type"><a href="class_goog_html_SafeUrl.html">goog.html.SafeUrl</a></span>
      </div>


     <div class="entryOverview">
       Creates a SafeUrl object from <code> url</code>. If <code> url</code> is a
goog.html.SafeUrl then it is simply returned. Otherwise the input string is
validated to match a pattern of commonly used safe URLs. The string is
converted to UTF-8 and non-whitelisted characters are percent-encoded. The
string wrapped by the created SafeUrl will thus contain only ASCII printable
characters.

<code> url</code> may be a URL with the http, https, or mailto scheme,
or a relative URL (i.e., a URL without a scheme; specifically, a
scheme-relative, absolute-path-relative, or path-relative URL).

<code> url</code> is converted to UTF-8 and non-whitelisted characters are
percent-encoded. Whitelisted characters are '%' and, from RFC 3986,
unreserved characters and reserved characters, with the exception of '\'',
'(' and ')'. This ensures the the SafeUrl contains only ASCII-printable
characters and reduces the chance of security bugs were it to be
interpolated into a specific context without the necessary escaping.

If <code> url</code> fails validation or does not UTF-16 decode correctly
(JavaScript strings are UTF-16 encoded), this function returns a SafeUrl
object containing an innocuous string, goog.html.SafeUrl.INNOCUOUS_STRING.


     </div>


    <! -- Method details -->
    <div class="entryDetails">

      <div class="detailsSection">
        <b>Arguments: </b>






<table class="horiz-rule">
     
   <tr class="even">
     <td>
        <span class="entryName">url</span>
        : <span class="type"><a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/String">string</a></span><span>&nbsp;|&nbsp;</span><span>!</span><span class="type"><a href="interface_goog_string_TypedString.html">goog.string.TypedString</a></span>
        <div class="entryOverview">The URL to validate.</div>
     </td>
   </tr>
  </table>
      </div>
   
      <div class="detailsSection">
        <b>Returns:</b>&nbsp;<span>!</span><span class="type"><a href="class_goog_html_SafeUrl.html">goog.html.SafeUrl</a></span>&nbsp;
            The validated URL, wrapped as a SafeUrl.
      </div>
  
    </div>
   
  </td>


  <td class="view-code">
     <a href="local_closure_goog_html_safeurl.js.source.html#line302">code &raquo;</a>
  </td>
     </tr>


     <tr class="even entry public">
       <td class="access"></td>






  <td>
    <a name="goog.html.SafeUrl.unwrap"></a>


     <div class="arg">
       <img align="left" src="static/images/blank.gif">

        <span class="entryNamespace">goog.html.SafeUrl.</span><span class="entryName">unwrap<span class="args">(<span class="arg">safeUrl</span>)</span>
        </span>
        &#8658; <span class="type"><a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/String">string</a></span>
      </div>


     <div class="entryOverview">
       Performs a runtime check that the provided object is indeed a SafeUrl
object, and returns its value.

IMPORTANT: The guarantees of the SafeUrl type contract only extend to the
behavior of  browsers when interpreting URLs. Values of SafeUrl objects MUST
be appropriately escaped before embedding in a HTML document. Note that the
required escaping is context-sensitive (e.g. a different escaping is
required for embedding a URL in a style property within a style
attribute, as opposed to embedding in a href attribute).

Note that the returned value does not necessarily correspond to the string
with which the SafeUrl was constructed, since goog.html.SafeUrl.sanitize
will percent-encode many characters.


     </div>


    <! -- Method details -->
    <div class="entryDetails">

      <div class="detailsSection">
        <b>Arguments: </b>






<table class="horiz-rule">
     
   <tr class="even">
     <td>
        <span class="entryName">safeUrl</span>
        : <span>!</span><span class="type"><a href="class_goog_html_SafeUrl.html">goog.html.SafeUrl</a></span>
        <div class="entryOverview">The object to extract from.</div>
     </td>
   </tr>
  </table>
      </div>
   
      <div class="detailsSection">
        <b>Returns:</b>&nbsp;<span class="type"><a href="https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/String">string</a></span>&nbsp;
            The SafeUrl object's contained string, unless the run-time
    type check fails. In that case, <code> unwrap</code> returns an innocuous
    string, or, if assertions are enabled, throws
    <code> goog.asserts.AssertionError</code>.
      </div>
  
    </div>
   
  </td>


  <td class="view-code">
     <a href="local_closure_goog_html_safeurl.js.source.html#line204">code &raquo;</a>
  </td>
     </tr>


  </table>
</div>






      <!-- Column 1 end -->
    </div>

        <div class="col2">
          <!-- Column 2 start -->
          <div class="col2-c">
            <h2 id="ref-head">Directory html</h2>
            <div id="localView"></div>
          </div>

          <div class="col2-c">
            <h2 id="ref-head">File Reference</h2>
            <div id="sideFileIndex" rootPath="" current="/goog/html/safeurl.js"></div>
          </div>
          <!-- Column 2 end -->
        </div>
</div>
</div>

</body>
</html>
